HealthStatistics#

The HealthStatistics class provides an interface for analyzing aggregated health quantity data over a specified time range. It allows you to compute key statistical values such as:

• Total duration
• Average, sum, minimum, maximum quantities
• Most recent value and its date range

This class is ideal for generating summaries of daily, weekly, or custom health data intervals.

Overview#

Each HealthStatistics instance represents statistics for a specific HealthQuantityType within a defined startDate and endDate range. You can optionally filter statistics by a HealthSource (e.g., only include samples recorded by a specific device or app).

Properties#

Methods#

duration(unit: HealthUnit, source?: HealthSource): number | null#

Returns the total accumulated duration of all samples within the range.

• unit: The unit of time to return the duration in (e.g., seconds, minutes).
• source (optional): If provided, only samples from that source will be included.

Returns null if no matching samples are found.

averageQuantity(unit: HealthUnit, source?: HealthSource): number | null#

Returns the average quantity value of all samples.

• unit: The unit to express the average in (e.g., HealthUnit.bpm()).
• source (optional): Filter samples by source.

sumQuantity(unit: HealthUnit, source?: HealthSource): number | null#

Returns the total sum of quantity values over the date range.

minimumQuantity(unit: HealthUnit, source?: HealthSource): number | null#

Returns the minimum recorded value in the given unit.

maximumQuantity(unit: HealthUnit, source?: HealthSource): number | null#

Returns the maximum recorded value in the given unit.

mostRecentQuantity(unit: HealthUnit, source?: HealthSource): number | null#

Returns the most recent quantity value recorded within the range. If no values are available, returns null.

mostRecentQuantityDateInterval(source?: HealthSource): HealthDateInterval | null#

Returns a HealthDateInterval object indicating the start and end time of the most recent recorded value. Useful for knowing when the last data point was recorded.

Example Usage#

1const stats = await Health.queryStatistics({
2  type: "stepCount",
3  startDate: new Date("2025-07-01"),
4  endDate: new Date("2025-07-02")
5})
6
7const totalSteps = stats.sumQuantity(HealthUnit.count())
8const average = stats.averageQuantity(HealthUnit.count())
9const mostRecent = stats.mostRecentQuantity(HealthUnit.count())
10const recentInterval = stats.mostRecentQuantityDateInterval()
11
12console.log("Steps Summary:")
13console.log("Total:", totalSteps)
14console.log("Average:", average)
15console.log("Most Recent:", mostRecent)
16console.log("Interval:", recentInterval)

HealthSource Class#

The HealthSource class represents the origin of a HealthKit sample. It is typically an app or device that generated or synced the health data.

Properties#

Static Methods#

HealthSource.forCurrentApp(): HealthSource#

Returns a HealthSource object representing the current Scripting app. This can be used to filter statistics only for data recorded or synced by your app.

Example: Filtering by Source#

1const stats = await Health.queryStatistics("heartRate", {
2  startDate: new Date("2025-07-01"),
3  endDate: new Date("2025-07-02")
4})
5
6const currentAppSource = HealthSource.forCurrentApp()
7const averageHR = stats.averageQuantity(HealthUnit.countPerMinute(), currentAppSource)
8
9console.log("Heart rate from this app:", averageHR)

Summary#

• HealthStatistics helps you analyze trends over time by calculating averages, totals, and most recent values.
• Supports optional filtering by source using HealthSource.
• Useful for building visual health summaries and dashboards based on HealthKit data.